Each integrated chain has its own factory contract. These contracts will be created by Euclid whenever an integration with a new chain occurs.
You can read about the factory architecture here .
Execute Messages
List of execute messages that can be performed on the Factory contract.
Swap Request
The asset_in
is the token being swapped from, and asset_out
is the token you want to receive. Cross-chain support is built in via the cross_chain_addresses
field.
Solidity JSON
function swap_request (
CrossChainUser memory sender ,
TokenWithDenom memory asset_in ,
uint256 amount_in ,
string memory asset_out ,
uint256 min_amount_out ,
NextSwapPair [ ] memory swaps ,
CrossChainUserWithLimit [ ] memory cross_chain_addresses ,
PartnerFee memory partnerFee ,
string memory meta
) external ;
{
"swap_request" : {
"sender" : {
"chain_uid" : "ethereum" ,
"address" : "0xabc123abc123abc123abc123abc123abc123abcd"
} ,
"asset_in" : {
"token" : "usdc" ,
"token_type" : {
"native" : {
"denom" : "usdc"
}
}
} ,
"amount_in" : "1000000" ,
"asset_out" : "dai" ,
"min_amount_out" : "990000" ,
"swaps" : [
{
"token_in" : "usdc" ,
"token_out" : "weth"
} ,
{
"token_in" : "weth" ,
"token_out" : "dai"
}
] ,
"cross_chain_addresses" : [
{
"user" : {
"chain_uid" : "arbitrum" ,
"address" : "0xdef456def456def456def456def456def456abcd"
} ,
"limit" : "800000"
}
] ,
"partner_fee" : {
"partner_fee_bps" : 25 ,
"recipient" : "0xgkhj33..."
}
}
}
Field Type Description sender
CrossChainUser
Optional user to execute the swap on behalf of. Typically, you do not need to specify a sender
field. Users send tokens directly with their transaction. However, in cross-chain transactions involving IBC (where asynchronous behavior happens), external contracts may want to trigger swaps and have vouchers minted directly to a user instead of the contract itself. In these cases, setting sender
allows the final minted vouchers to be credited properly. asset_in
TokenWithDenom
The token being used as input for the swap. amount_in
uint256
Amount of asset_in
to swap. For native assets, this is overridden by msg.value
. asset_out
string
Target token the user wants to receive. min_amount_out
uint256
Minimum amount of the output asset for the swap to be considered a success. Used to specify maximum slippage accepted. swaps
NextSwapPair[]
The different swaps to get from asset_in to asset_out. This could be a direct swap or multiple swaps. For example, if swapping from token A to B, the swaps can be A -> B directly, or A -> C then C-> D then D->B. Usually the most efficient route is used. cross_chain_addresses
CrossChainUserWithLimit[]
A set of addresses to specify where the asset_out should be released. The first element specified in the vector has highest priority and so on. User specifies a limit for each provided address which indicates the amount of funds that should be released to that address. In case there are any leftover funds, they are added to the user's virtual balance for the address that initiated the swap. If limit is not specified, then the maximum amount is taken. partner_fee
PartnerFee
Optional partner fee information for swaps. The maximum fee that can be set is 30 (0.3%). meta
string
Optional metadata field for tracking or sequencing.
With the following structs:
Solidity
struct NextSwapPair {
string token_in ;
string token_out ;
}
// The percentage of the fee for the platform. Specified in basis points (bps)
// Example: 1 = 0.01%, 30 = 0.3%, 10000 = 100%
struct PartnerFee {
uint64 partner_fee_bps ; // Max 30 (0.3%)
address recipient ; // Address to receive the fee
}
Struct Field Type Description NextSwapPair
token_in
string
The input token in the swap segment. token_out
string
The output token in the swap segment. PartnerFee
partner_fee_bps
uint64
Fee percentage in basis points (max 30 = 0.3%). recipient
address
Address that receives the partner/referral fee.
Deposit Token
Used to deposit tokens into the protocol and receive voucher tokens in return. Supports native and smart tokens.
Solidity JSON
function depositToken (
TokenWithDenom memory asset_in ,
uint256 amount_in ,
CrossChainUser memory recipientOpt
) external ;
{
"deposit_token" : {
"asset_in" : {
"token" : "usdc" ,
"token_type" : {
"native" : {
"denom" : "usdc"
}
}
} ,
"amount_in" : "500000" ,
"recipient" : {
"chain_uid" : "amoy" ,
"address" : "0xfeed123feed123feed123feed123feed123abcd"
}
}
}
Field Type Description asset_in
TokenWithDenom
The asset being exchanged into vouchers. amount_in
uint256
Amount of the token to deposit. recipient
CrossChainUser
Optional recipient for the voucher tokens. Defaults to the sender if omitted.
Withdraw Virtual Balance
This message lets users withdraw voucher tokens and release them to one or more cross-chain addresses.
Solidity JSON
function withdrawVirtualBalance (
string memory token ,
uint128 amount ,
CrossChainUserWithLimit [ ] memory cross_chain_addresses
) external ;
{
"withdraw_virtual_balance" : {
"token" : "dai" ,
"amount" : "250000" ,
"cross_chain_addresses" : [
{
"user" : {
"chain_uid" : "ethereum" ,
"address" : "0x00112233445566778899aabbccddeeff00112233"
} ,
"limit" : "200000"
} ,
{
"user" : {
"chain_uid" : "optimism" ,
"address" : "0x445566778899aabbccddeeff0011223344556677"
}
}
]
}
}
Field Type Description token
string
ID of the voucher token to withdraw. amount
uint128
The amount of voucher tokens to withdraw. cross_chain_addresses
CrossChainUserWithLimit[]
List of destination addresses to receive the withdrawn funds.
Transfer Virtual Balance
Transfers voucher tokens from the sender’s virtual balance to another user on a specific chain.
Solidity JSON
function transferVirtualBalance (
string memory token ,
uint256 amount ,
CrossChainUser memory recipient_address
) external ;
{
"transfer_virtual_balance" : {
"token" : "dai" ,
"amount" : "150000" ,
"recipient_address" : {
"chain_uid" : "amoy" ,
"address" : "0xaabbccddeeff0011223344556677889900aabbcc"
}
}
}
Field Type Description token
string
The voucher token ID to transfer. amount
uint256
Amount of virtual balance to transfer. recipient_address
CrossChainUser
Target address and chain to receive the tokens.
Add Liquidity Request
Adds liquidity to a pool using a pair of tokens. User receives LP tokens representing their share in the pool. Supports native and smart tokens.
Solidity JSON
function addLiquidityRequest (
PairWithDenomAndAmount memory pair_info ,
uint64 slippage_tolerance_bps
) external ;
{
"add_liquidity_request" : {
"pair_info" : {
"token_1" : {
"token" : "usdc" ,
"amount" : "1000000" ,
"token_type" : {
"native" : {
"denom" : "usdc"
}
}
} ,
"token_2" : {
"token" : "dai" ,
"amount" : "1000000" ,
"token_type" : {
"smart" : {
"contract_address" : "0x5f123abc123abc123abc123abc123abc123abcde"
}
}
}
} ,
"slippage_tolerance_bps" : 300
}
}
Field Type Description pair_info
PairWithDenomAndAmount
Token pair and amounts to add as liquidity. slippage_tolerance_bps
uint64
Max slippage tolerated in basis points (e.g., 300
= 3%).
Remove Liquidity Request
Removes liquidity from a pool and sends the tokens to one or more cross-chain addresses based on the user's allocation preferences.
Solidity JSON
function removeLiquidityRequest (
Pair memory pair ,
uint256 lp_allocation ,
CrossChainUserWithLimit [ ] memory cross_chain_addresses
) external ;
{
"remove_liquidity_request" : {
"pair" : {
"token_1" : "usdc" ,
"token_2" : "dai"
} ,
"lp_allocation" : "100000000000" ,
"cross_chain_addresses" : [
{
"user" : {
"chain_uid" : "amoy" ,
"address" : "0xfeed123feed123feed123feed123feed123abcd"
} ,
"limit" : "500000"
} ,
{
"user" : {
"chain_uid" : "arbitrum" ,
"address" : "0xdef456def456def456def456def456def456abcd"
}
}
]
}
}
Field Type Description pair
Pair
The token pair for the pool you want to remove liquidity from. lp_allocation
uint256
Amount of LP tokens to redeem. cross_chain_addresses
CrossChainUserWithLimit[]
Where to send the redeemed tokens. First entry has the highest priority.
Request Pool Creation
Sends a request to create a new liquidity pool for a given token pair. The user defines the pool configuration and LP token metadata.
Solidity JSON
function request_pool_creation (
PairWithDenomAndAmount memory pair ,
uint64 slippage_tolerance_bps ,
string memory lp_token_name ,
string memory lp_token_symbol ,
uint8 lp_token_decimal
) external ;
{
"request_pool_creation" : {
"pair" : {
"token_1" : {
"token" : "usdc" ,
"amount" : "500000" ,
"token_type" : {
"native" : {
"denom" : "usdc"
}
}
} ,
"token_2" : {
"token" : "dai" ,
"amount" : "500000" ,
"token_type" : {
"smart" : {
"contract_address" : "0x9876543210abcdef9876543210abcdef98765432"
}
}
}
} ,
"slippage_tolerance_bps" : 200 ,
"lp_token_name" : "USDC-DAI Pool Token" ,
"lp_token_symbol" : "USDCDAI-LP" ,
"lp_token_decimal" : 18
}
}
Field Type Description pair
PairWithDenomAndAmount
Token pair and amounts used to initialize the pool. slippage_tolerance_bps
uint64
Max slippage allowed when creating the pool (in basis points). lp_token_name
string
Full name of the LP token. lp_token_symbol
string
Symbol (ticker) of the LP token. lp_token_decimal
uint8
Number of decimals used by the LP token.
Query Messages
List of queries that can be performed on the Factory contract.
Get State
Queries the configuration and current status of the Factory contract.
Query Call
Solidity JSON
function getState ( ) external view returns ( State memory ) ;
Response
Solidity
struct State {
string chain_uid ;
address router ;
address admin ;
uint256 escrow_code_id ;
uint256 voucher_token_code_id ;
bool is_native ;
DenomFees partner_fees_collected ;
}
struct DenomFees {
string [ ] denoms ;
uint256 [ ] amounts ;
}
Field Type Description chain_uid
string
Unique chain ID (e.g., "amoy", "ethereum"). router
address
Address of the router contract. admin
address
Address of the factory admin. escrow_code_id
uint256
Code ID for escrow contract deployment. voucher_token_code_id
uint256
Code ID for voucher token contracts. is_native
bool
Whether the factory is native to this chain. partner_fees_collected
DenomFees
Fee totals per denom collected from partner fees.
Get All Tokens
Returns a list of all token IDs registered in the factory.
Query Call
Solidity JSON
function getAllTokens ( ) external view returns ( string [ ] memory ) ;
Response
Field Type Description tokens
string[]
List of registered token IDs.
Get Partner Fees Collected
Returns the total amount of partner fees collected by the protocol, grouped by token denomination.
Query Call
Solidity JSON
function getPartnerFeesCollected ( ) external view returns ( DenomFees memory ) ;
{
"get_partner_fees_collected" : { }
}
Response
Solidity
struct DenomFees {
string [ ] denoms ;
uint256 [ ] amounts ;
}
Field Type Description denoms
string[]
Array of token denoms (e.g., usdc
, dai
). amounts
uint256[]
Total amount collected for each corresponding denom.
Get LP Token
Returns the address of the LP (liquidity provider) token for the specified VLP contract.
Query Call
Solidity JSON
function getLPToken ( address vlp ) external view returns ( address ) ;
{
"get_l_p_token" : {
"vlp" : "nibi..."
}
}
Field Type Description vlp
address
The address of the liquidity pool (VLP).
Response
Solidity
address lp_token_address ;
Field Type Description lp_token_address
address
The ERC20 contract address of the LP token.
Get VLP
Returns the VLP contract address for a given token pair.
Query Call
Solidity JSON
function getVlp ( Pair memory pair ) external view returns ( address ) ;
{
"get_vlp" : {
"pair" : {
"token_1" : "usdc" ,
"token_2" : "dai"
}
}
}
Field Type Description token_1
string
ID of the first token in the pair. token_2
string
ID of the second token in the pair.
Response
Field Type Description vlp_address
address
Address of the VLP contract for the given pair.
Get VLP
Returns the VLP contract address for a given token pair.
Query Call
Solidity JSON
function getVlp ( Pair memory pair ) external view returns ( address ) ;
{
"get_vlp" : {
"pair" : {
"token_1" : "usdc" ,
"token_2" : "dai"
}
}
}
Field Type Description token_1
string
ID of the first token in the pair. token_2
string
ID of the second token in the pair.
Response
Field Type Description vlp_address
address
Address of the VLP contract for the given pair.
Get All Pools
Returns all registered liquidity pools and their associated token pairs.
Query Call
Solidity JSON
function getAllPools ( ) external view returns ( PoolVlpResponse [ ] memory ) ;
struct PoolVlpResponse {
Pair pair ;
address vlp ;
}
Response
Solidity
struct PoolVlpResponse {
Pair pair ;
address vlp ;
}
struct Pair {
string token_1 ;
string token_2 ;
}
Field Type Description pair.token_1
string
First token in the liquidity pair. pair.token_2
string
Second token in the liquidity pair. vlp
address
The address of the corresponding VLP contract.
Get Escrow
Returns the escrow contract address and token types for a given token ID.
Query Call
Solidity JSON
function getEscrow ( string memory token_id ) external view returns ( EscrowResponse memory ) ;
struct EscrowResponse {
address escrow_address ;
TokenType [ ] token_types ;
}
{
"get_escrow" : {
"token_id" : "usdc"
}
}
Field Type Description token_id
string
The token ID to look up escrow for.
Response
Solidity
struct EscrowResponse {
address escrow_address ;
TokenType [ ] token_types ;
}
Field Type Description escrow_address
address
Address of the escrow contract (if any). token_types
TokenType[]
Supported token types backing this token ID.